home *** CD-ROM | disk | FTP | other *** search
/ NeXT Enterprise Objects Framework 1.1 / NeXT Enterprise Objects Framework 1.1.iso / NextDeveloper / Headers / foundation / NSData.h < prev    next >
Encoding:
Text File  |  1994-05-14  |  6.0 KB  |  177 lines
  1. /*    NSData.h
  2.     Object container for bags of bytes
  3.       Copyright 1993, 1994, NeXT, Inc.
  4.     NeXT, April 1993
  5. */
  6.  
  7. #import <foundation/NSObject.h>
  8. #import <foundation/NSRange.h>
  9.  
  10. /* The motivation for this interface is
  11.     - to have an object cover for bags of bytes
  12.     - to hide low-level vm primitives (e.g. the difference between malloc() and vm_allocate())
  13. */
  14.  
  15. /***************    Read only Abstract Class        ***********/
  16.  
  17. @interface NSData:NSObject <NSCopying, NSMutableCopying>
  18. /* NOTES:
  19.     -copyWithZone: and -copy guarantee an immutable returned value;
  20.     -isEqual: checks argument is an NSData, and then byte-for-byte identity;
  21.     NSData objects are always encoded/decoded as PList.  Therefore mutability and class are not preserved for distribution or persistency.
  22.      */
  23.  
  24. - (unsigned)length;
  25.     /* The number of bytes in the bag of bytes */
  26.     
  27. - (const void *)bytes;
  28.     /* Direct access to the bag of bytes; Read-only */
  29.  
  30. @end
  31.  
  32. @interface NSData (NSExtendedData)
  33.  
  34. - (NSData *)subdataWithRange:(NSRange)range;
  35.     /* Returns an NSData that snapshots a range; 
  36.     [self length] must be greater than range.location + range.length;
  37.     Very efficient: no copy of the bytes is done if initial range is immutable, and if big mutable are virtually copied */
  38.      
  39. - (void)getBytes:(void *)buffer;
  40.     /* Copies all the bytes into buffer; Efficient (virtual) copy will be done if appropriate */
  41.     
  42. - (void)getBytes:(void *)buffer length:(unsigned)length;
  43.     /* Copies bytes (but at most length) into buffer; 
  44.     Given length is the maximum length of the buffer, the bag of bytes may hold fewer bytes;
  45.     Efficient (virtual) copy will be done if appropriate */
  46.  
  47. - (void)getBytes:(void *)buffer range:(NSRange)range;
  48.     /* Copies bytes (but at most length) into buffer; 
  49.     Range start needs to be within the bag of bytes;
  50.     Efficient (virtual) copy will be done if appropriate */
  51.  
  52. - (BOOL)writeToFile:(NSString *)path atomically:(BOOL)useAuxiliaryFile;
  53.     /* writes a given file, using a ~ file if useAuxiliaryFile (to have atomic update of file);
  54.     returned value indicates success */
  55.  
  56. - (BOOL)isEqualToData:(NSData *)other;
  57.     /* Byte-for-byte identity check */
  58.  
  59. - (NSString *)description;
  60.     /* Produces a string that can be read by the ASCII parser */
  61.  
  62. @end
  63.  
  64. /***************    Read/Write Abstract Class    ***************/
  65.  
  66. @interface NSMutableData:NSData
  67.  
  68. - (void *)mutableBytes;
  69.     /* Returns a pointer to the bag of bytes that can be used for writing;
  70.     [data mutableBytes] is identical to [data bytes] (but types differ) */
  71.  
  72. - (void)setLength:(unsigned)length;
  73.     /* Can be used to truncate or to extend; 
  74.     When extending, the extension area is zero-filled */
  75.  
  76. @end
  77.  
  78. @interface NSMutableData (NSExtendedMutableData)
  79.  
  80. - (void)replaceBytesInRange:(NSRange)range withBytes:(const void *)bytes;
  81.     /* Substitutes bytes; 
  82.     Range start needs to be within the bag of bytes or just at the end;
  83.     Efficient (virtual) copy will be done if appropriate */
  84.  
  85. - (void)resetBytesInRange:(NSRange)range;
  86.     /* Substitutes zeros in range; 
  87.     Range start needs to be within the bag of bytes or just at the end;
  88.     Efficient (virtual) copy will be done if appropriate */
  89.  
  90. - (void)appendBytes:(const void *)bytes length:(unsigned)length;
  91.     /* Appends bytes; 
  92.     Efficient (virtual) copy will be done if appropriate */
  93.  
  94. - (void)appendData:(NSData *)other;
  95.     /* Appends another bag of bytes */
  96.  
  97. - (void)increaseLengthBy:(unsigned)extraLength;
  98.     /* appends a zero-filled area of length extraLength;
  99.     Efficient shortcut for [self setLength:[self length]+extraLength] */
  100.  
  101. @end
  102.  
  103. /***************    Immutable Creation        ***************/
  104.  
  105. @interface NSData (NSDataCreation)
  106.  
  107. + allocWithZone:(NSZone *)zone;
  108.     /* Create an uninitialized instance of a concrete class;
  109.     substitutes a concrete class if called with NSData;
  110.     +alloc can also be used to that effect */
  111.  
  112. + data;
  113.     /* Creates an autorelease empty bag of bytes; 
  114.     mostly useful when called with NSMutableData */
  115.  
  116. + dataWithBytes:(const void *)bytes length:(unsigned)length;
  117.     /* Creates an autorelease bag of bytes; 
  118.     leaves bytes untouched */
  119.  
  120. + dataWithBytesNoCopy:(void *)bytes length:(unsigned)length;
  121.     /* Creates an autorelease bag of bytes; 
  122.     bytes will be freed using free() when data is released */
  123.  
  124. + dataWithContentsOfFile:(NSString *)path;
  125.     /* Creates an autorelease bag of bytes; 
  126.     reads all bytes from given file; file is opened and closed;
  127.     returns nil on error */
  128.  
  129. + dataWithContentsOfMappedFile:(NSString *)path;
  130.     /* Creates an autorelease bag of bytes; 
  131.     reads all bytes from given file; file is mapped.
  132.     Because of file mapping restrictions, this should only be used if file is guaranteed to exist until data disappears*/
  133.  
  134. - initWithBytesNoCopy:(void *)bytes length:(unsigned)length;
  135.     /* bytes will be freed using free() upon freeing of object;
  136.     designated initializer */
  137.  
  138. - initWithBytes:(const void *)bytes length:(unsigned)length;
  139.     /* leaves bytes untouched */
  140.     
  141. - initWithData:(NSData *)data;
  142.  
  143. - initWithContentsOfFile:(NSString *)path;
  144.     /* reads all bytes from given file; file is opened and closed;
  145.     returns nil on error */
  146.     
  147. - initWithContentsOfMappedFile:(NSString *)path;
  148.     /* reads all bytes from given file; file is mapped.
  149.     Because of file mapping restrictions, this should only be used if file is guaranteed to exist until data disappears*/
  150.     
  151. @end
  152.  
  153. /***************    Mutable Creation        ***********/
  154.  
  155. @interface NSMutableData (NSMutableDataCreation)
  156.  
  157. + allocWithZone:(NSZone *)zone;
  158.     /* Create an uninitialized instance of a concrete class;
  159.     substitutes a concrete class if called with NSMutableData;
  160.     +alloc can also be used to that effect */
  161.      
  162. + dataWithCapacity:(unsigned)aNumItems;
  163.     /* Creates an autoreleased mutable data;
  164.     aNumItems is only a hint */
  165.  
  166. + dataWithLength:(unsigned)length;
  167.     /* Creates an autoreleased mutable data, zero-filled */
  168.  
  169. - initWithCapacity:(unsigned)capacity;
  170.     /* just a hint for ultimate length; length is set to 0 */
  171.  
  172. - initWithLength:(unsigned)length;
  173.     /* provides zero-fill data of length length*/
  174.  
  175. @end
  176.  
  177.